void gl_histadd(char *line);
void gl_setwidth(int width);
void gl_strwidth(int (*width_func)());
extern int (*gl_in_hook)(char *buf);
extern int (*gl_out_hook)(char *buf);
extern int (*gl_tab_hook)(char *buf,
int prompt_width, int *cursor_loc);
Programming Interface
getline
returns a pointer to a line of text read from the user,
prompting the user with the specified
prompt.
The pointer refers to a static buffer allocated by the
getline
package.
Clients may assume that the pointer
getline
returns is always the same, and is never NULL.
The buffer
getline
returns to the caller contains the terminating newline character,
except on end of file,
in which case the first character in the buffer is 0
(NUL).
File descriptors 0 and 1 must be connected to the terminal
(not redirected),
so the caller should check for this condition (using
isatty())
and call stdio routines if the session is not interactive.
gl_histadd adds the given line to the getline history list if the line is not empty and if it is different from the last line in the history list (so the caller need not check for these conditions). gl_histadd makes its own copies of all the lines it adds to the history list. This is so the caller can reuse the buffer it supplies to gl_histadd.
gl_setwidth specifies the terminal width to use for horizontal scrolling. The default value is 80 columns, and it is important to properly specify the width or lines may wrap inadvertently.
gl_strwidth allows the application program to supply a prompt string width calculation function that returns the number of screen positions used by the argument string. By default strlen is used, but if the prompt contains escape sequences the user can bind a function that returns the actual number of screen postitions used by the argument string, not including the escape characters.
In addition to the function call interface, getline has three externally accessible function pointers that act as hooks if bound to user-defined functions. getline supplies each of the functions with a pointer to the current buffer as the first argument, and expects the return value to be the index of the first change the function made in the buffer (or -1 if the function did not alter the buffer). After the functions return, getline updates the screen as necessary. Note that the functions may not alter the size of the buffer. Indeed, they do not even know how large the buffer is!
getline calls gl_in_hook (initially NULL) each time it loads a new buffer. More precisely, this is
getline calls gl_out_hook (initially NULL) when a line has been completed by the user entering a NEWLINE (^J) or RETURN (^M). The buffer gl_out_hook sees does not yet have the newline appended, and gl_out_hook should not add a newline.
getline calls gl_tab_hook whenever the user types a TAB. In addition to the buffer, getline supplies the current prompt_width (presumably needed for tabbing calculations) and cursor_loc, a pointer to the cursor location. (*cursor_loc = 0 corresponds to the first character in the buffer) *cursor_loc tells gl_tab_hook where the TAB was typed. Note that when it redraws the screen, getline will honor any change gl_tab_hook may make to *cursor_loc. Note also that prompt_width may not correspond to the actual width of prompt on the screen if prompt contains escape sequences. gl_tab_hook is initially bound to the getline internal static function gl_tab, which acts like a normal TAB key by inserting spaces.
User Interface
To edit, the user moves the cursor to the point needing correction and
then inserts or deletes characters or words as needed.
All the editing commands are control characters,
which typed by holding the
CTRL key down while typing another character.
Control characters are indicated below as the caret
(^)
followed by another character,
such as
^A.
All edit commands operate from any place on the line, not just at the beginning.
These are the getline key bindings.
getline recognizes DOS and ANSI arrow keys. They cause the following actions: up is the same as ^P, down is the same as ^N, left is the same as ^P, and right is the same as ^F.
Program by Christopher R. Thewalt (thewalt@ce.berkeley.edu)
Original man page by DaviD W. Sanderson (dws@cs.wisc.edu) and Christopher R. Thewalt